Graphics Plus

home *** CD-ROM | disk | FTP | other *** search

/ Graphics Plus / Graphics Plus.iso / msdos / editors / chiaro / gifstrip.doc < prev next >

Wrap

Text File | 1993-03-12 | 30KB | 740 lines

GIFSTRIP 2.2 DOCUMENTATION ========================== James W. Birdsall 03/19/93 0. CONTENTS ----------- 0. CONTENTS 1. INTRODUCTION 1.1 Quick Reference 1.2 Copyright, License, and Warranty Disclaimer 2. USAGE 2.1 Targets 2.1.1 Wildcards 2.2 Options 2.2.1 Output redirection options 2.2.2 Rebuilding and processing options 2.2.3 Temporary Storage Options 2.2.4 -# Version 2.2.5 -? Help 3. OUTPUT 3.1 File Header Line 3.2 Internal Section Lines 3.2.1 Image 3.2.2 Extension Block 3.2.3 Other Lines 3.3 Terminator Line 3.4 No Rebuild 3.5 Rebuild 3.6 Examples 4. THE END 1. INTRODUCTION --------------- GIFSTRIP is a program of the Chiaro suite. It removes excess characters, if present, from GIF-format image files. Excess characters may be added in a variety of ways, including XMODEM-protocol file transfers or transfer from a Macintosh computer. I have observed files with anywhere from one byte to 13K of excess characters; in the latter case, the size of the file was almost doubled. GIFSTRIP also does some basic file analysis and enforces a few format requirements which are sometimes ignored. For temporary storage, it can use disk files and most types of memory. By default, it uses all available types of memory first and only uses disk space to make up the shortfall if there is not enough space available among all the different types of memory (see section 2.2.3 for a more detailed discussion). By default, GIFSTRIP also keeps the original file around until the new file has been written to disk successfully (see section 2.2.2 for a more detailed discussion). 1.1 Quick Reference ------------------- This is a quick summary of the usage and options of GIFSTRIP. Invoking GIFSTRIP with the option "-?" will produce a similar summary. Complete explanations may be found in section 2. usage: gifstrip [options] target [target ...] target filename, filename with wildcards, or path. Wildcards are *, ?, and ranges or groups specified in []. A range or group may be complemented with ^ or !. -b BATCH: suppresses all console output. Should be first on the line. Returns ERRORLEVEL 0 if OK or stripped OK, 1 if a non-GIF file was found, 2 if the GIF file ended unexpectedly, or 3 on error. -r Sends error messages to stderr instead of stdout. -f Forces rebuild. Normally file is not rebuilt if no extra characters are found and file meets format requirements. -n Disables strict format requirements. -m Enables checking for leading junk characters (from a Mac, for example). -o Causes the original file to be erased before the new file is written to disk. This is useful if the disk is nearly full and there is not enough room for two copies of the file. -c Do not use CONVENTIONAL memory for temporary storage. -e Do not use EMS memory for temporary storage. -x Do not use XMS memory for temporary storage. -d Do not use DISK for temporary storage. -s Use ONLY DISK for temporary storage. Equivalent to the combination -c -e -x. -tpath Specify path for DISK temporary storage. -# VERSION: Prints version information on internal modules, then exits. GIFSTRIP automatically reads a list of targets from stdin if stdin is redirected. Targets must be separated by newlines, and are wildcard-expanded in the same way as command-line targets. Note that command-line targets are ignored if stdin is redirected; if stdin is not redirected, there must be at least one target on the command line. Note that at least one of conventional, EMS, XMS, or disk storage must be allowed. Options are case-insensitive, and may not be combined. 1.2 Copyright, License, and Warranty Disclaimer ----------------------------------------------- The Graphics Interchange Format(c) is the Copyright property of CompuServe Incorporated. GIF(sm) is a Service Mark property of CompuServe Incorporated. GIFSTRIP is not in the public domain. All the files are copyright 1993 by James W. Birdsall, all rights reserved. The following license applies to the entire Chiaro suite, which is made up of all the files listed in the file MANIFEST. Permission is granted to do the following: You may freely redistribute this archive, so long as it contains all the files listed in the file MANIFEST, intact and unmodified. You may use the programs contained in this archive for a period of 30 days for evaluation purposes. Payment of the $10 shareware fee (which covers all the programs in the Chiaro suite) licenses you to use the Chiaro suite beyond the evaluation period. This license-to-use specifically includes use by bulletin board systems and other commercial or private information services. Registered users will also receive update notices and bug reports, and are entitled to use future versions without further payment. The contents of the distribution archive, and all other related files, information, and services are provided "as is" and without warranty. To the extent permitted by applicable law, the author disclaims all warranties, express or implied, including but not limited to, any implied warranty of merchantability or fitness for a particular purpose. While effort has been made to ensure that the files, information, and services are accurate and correct, the author shall not be liable for damages arising out of the use of or inability to use this product, including but not limited to, loss of profit, data, or use of this software, or special, incidental, or consequential damages or other similar claims, even if the author has been specifically advised of the possibility of such damages. Some states do not allow the exclusion of incidental or consequential damages, so the foregoing limitation may not apply to you. Information on contacting the author is provided at the end of this file. 2. USAGE -------- GIFSTRIP may be called with zero or more options interspersed with zero or more targets. All options are scanned before any file searching is done, so order of options and targets is unimportant. If the standard input is not redirected, at least one target must be specified on the command line. If the standard input is redirected (is not the keyboard), GIFSTRIP will detect this and will attempt to read a list of targets, separated with newlines, from the standard input. Targets on the command line will be ignored, but options on the command line will be used. This feature is for use with the "front end" option of CHILS. GIFSTRIP requires 110,000 bytes of free conventional memory to run. Additional free conventional memory (and/or free EMS and/or XMS memory) improves performance. 2.1 Targets ----------- A target can consist of a filename (optionally with path), a path, or a filename with wildcards (again, optionally with path). In the case of a filename, that file is checked. In the case of a path, all files in the specified directory are checked. In the case of a filename with wildcards, all files in the appropriate directory (the current directory if no path is given) matching the wildcards are checked. If a file that is checked is a GIF format file, it is processed. If it is not, it is not processed. 2.1.1 Wildcards --------------- Wildcards are much closer to the UNIX standard than the MS-DOS standard. The characters * and ? retain their ordinary meanings but matching is much more intelligent. For example, *A.GIF will match LENNA.GIF but not CHESS.GIF, whereas under ordinary MS-DOS wildcards, *A.GIF would match both. Further, groups and ranges of characters may be specified in brackets []. For example, PIC0[1-5].GIF will match any filename starting with "PIC0", then containing any one of the characters "1", "2", "3", "4", or "5", and ending with ".GIF". PIC0[1-5A-F].GIF will match the names described before or those with the characters "A", "B", "C", "D", "E", or "F" between "PIC0" and ".GIF". A range or group may be complemented with the characters "^" or "!". For example, PIC0[^1-5].GIF will match any name with one character between "PIC0" and ".GIF" unless that character is "1", "2", "3", "4", or "5". Note that wildcards are only allowed in the filename portion, not the path portion. "\PICTURES\NEWGIF*\*.GIF" is illegal and an error message will be issued. 2.2 Options ----------- GIFSTRIP has a variety of options to modify its function, including options to control the types of temporary storage used, the level of processing done, etc. These options are described below. Options are case-insensitive ("-x" is the same as "-X") and may not be combined ("-xe" will not have the desired effect, since only the "-x" will be recognized; "-x -e" should be used instead). 2.2.1 Output redirection options -------------------------------- The following options specify where various types of output should be sent. 2.2.1.1 -b Batch ---------------- The -b option causes GIFSTRIP to operate in batch mode. All console output is suppressed. This option should be first on the command line or other options may generate console output before this option is found. When in batch mode, GIFSTRIP adjusts the ERRORLEVEL return to reflect the results of processing. ERRORLEVEL is set to: 0 if the file was a GIF format file and did not need stripping, or was stripped OK 1 if the file was not a GIF format file 2 if GIFSTRIP encountered an unexpected end-of-file 3 if there was any other error NOTE: the ERRORLEVEL reflects only the results of the last file processed. Therefore, in batch mode only one file should be specified on the command line. 2.2.1.2 -r Error Redirect ------------------------- Normally error messages are sent to the standard output stream, along with all other output from GIFSTRIP. However, error messages can be redirected to the standard error output stream with the -r option. This means that error messages will appear on the screen even if output is redirected to a file with the DOS ">" or "|" output redirection operators. Note that the error message will not appear in the file, however. 2.2.2 Rebuilding and processing options --------------------------------------- The following options determine when a file needs to be rebuilt, and how the rebuilding is done. 2.2.2.1 -f Forced Rebuild ------------------------- The -f option forces GIFSTRIP to rebuild the file. Normally, the file is rebuilt only if extra characters are found or if the file does not meet the format requirements. The format requirements are discussed under the -n NOSTRICT option below. 2.2.2.2 -n Nostrict ------------------- This option disables strict format checking. Normally, the following violations are checked for: (GIF87a only) Global or local color table sorted flag set. (GIF87a only) Aspect ratio value nonzero. (GIF87a, GIF89a) Local color table size given but local color table flag not set (no local color table). (GIF89a only) Local color table sorted flag set, but local color table not present. If the -n option is used, any of the violations listed above which are present in the original file will also be present in the rebuilt file if the file is rebuilt. If there are no extra characters and the -f option is not used, the file will not be rebuilt even if any of these violations are present. 2.2.2.3 -m Mac -------------- This option handles files which have junk bytes before the GIF format signature. These files are typically generated by the Macintosh computer, hence the name of the option. GIFSTRIP searches through the file, starting at the beginning, looking for the GIF format signature, and starts rebuilding the file when it finds it. 2.2.2.4 -o Overwrite -------------------- By default, when rebuilding GIFSTRIP retains the original file until the rebuilt file has been completely written to disk. Thus, in case of error, either the original file or the rebuilt file will exist on disk no matter when GIFSTRIP is aborted, providing a measure of security. However, sometimes it is necessary to process a file which is on a nearly-full drive, with insufficient room for a second copy of the file. This option causes GIFSTRIP to erase the original file before starting to write the rebuilt file. For maximum security, it is recommended that you use the -s option (described below) in conjunction with this option, but in order to do so you will need another drive which does have sufficient room and you will have to use the -t option (also described below) to place the temporary file on that drive, or GIFSTRIP will attempt to place the temporary file on the same drive, note that there isn't enough room, and refuse to process the original file. 2.2.3 Temporary Storage Options ------------------------------- GIFSTRIP supports a wide variety of temporary storage. It can use: conventional memory, expanded memory (LIM EMS version 3.0 or above), extended memory (only if an XMS driver is present; common XMS drivers are Microsoft's HIMEM.SYS and Quarterdeck's QEMM), or a temporary file on disk. It automatically detects the presence of EMS and XMS. These choices fall into two general categories: memory and disk. There are advantages and disadvantages associated with each. Memory is much faster. However, if there is a catastrophic malfunction while the file is being recopied, the file could be damaged if you are using the -o option without the -s option -- the original file has already been erased and the new file has not been completed yet. Disk is slower, but safer. If there is a catastrophic malfunction, the temporary file will still be present and intact. Options have been provided to allow the user to disable any of the types of temporary storage, and to relocate the temporary file in the case of disk storage. GIFSTRIP searches in this order: conventional, EMS, XMS, disk. It skips any types that have been disabled. If there is not enough available in one type, it uses all of that type and goes on to the next type, until the total of all types used is sufficient. It can handle multiple blocks of XMS. Note that at least one type of temporary storage must be available and enabled; also note that GIFSTRIP will not process a file for which it cannot allocate as many bytes of temporary storage as are in the original file. By default, all types that are available in the system are used. 2.2.3.1 -c Disable Conventional ------------------------------- This option disables use of conventional memory. 2.2.3.2 -e Disable EMS ---------------------- This option disables use of expanded (EMS) memory. 2.2.3.3 -x Disable XMS ---------------------- This option disables use of XMS memory. 2.2.3.4 -d Disable Disk ----------------------- This option disables use of disk for temporary storage. 2.2.3.5 -s Safety (use only disk) --------------------------------- This option disables use of all types of memory. It is equivalent to the combination -c -e -x. 2.2.3.6 -tpath Temporary File Path ---------------------------------- This option specifies a path for the disk temporary file. By default, the temporary file is placed in the same directory as the original file. There must not be a space between the -t and the path. The temporary file is always called "GIFSTRIP.$$$" regardless of location. 2.2.4 -# Version ---------------- This option is intended more for bug reporting purposes than anything else. It causes GIFSTRIP to print the version numbers and compilation dates of its component modules. No files are processed, and all other options are ignored. 2.2.5 -? Help ------------- This option, or any syntax error on the command line, causes a usage message to be displayed. No files are processed, and all other options are ignored. 3. OUTPUT --------- GIFSTRIP produces at least two lines of output for each file. In some cases, GIFSTRIP may produce several pages of output. For each file specified, GIFSTRIP outputs the line "Processing xxx...", where xxx is the name and path (if present) of the file. If the file is not a GIF format file, GIFSTRIP outputs the message "ERROR: File is not a GIF format file." and proceeds to the next file. 3.1 File Header Line -------------------- GIFSTRIP prints a line containing general information about the file. For example: GIF87A G-- 21463 250 x 200 @ 128 G:\JUNK\VLA.GIF GIF89A G-A 34256 320 x 200 @ 256 G:\JUNK\GLASS.GIF The first column is the format. The next column contains three flags. The first flag is "G" if the file contains a global color table, or "-" if it does not. The second flag is "S" if the global color table is sorted in order of decreasing importance, or "-" if it is not. It will always be "-" for GIF87a files. The third flag is "A" if an aspect ratio is specified, or "-" if it is not. It will always be "-" for GIF87a files. The third column is the size of the file in bytes. The next two columns, not including the 'x' which is present for formatting purposes only, are the width and height of the logical screen, in pixels. The next column, not counting the '@' which is present for formatting purposes only, is the number of colors in the global color table, if any. If there is no global color table, "---" is displayed. The last column is the filename. If GIFSTRIP encounters in the file header one of the format violations listed under the -n NOSTRICT option, and the -n option is not in effect, it will print a message describing the violation after the file header line. This message will start with "FYI:". 3.2 Internal Section Lines -------------------------- After the file header line, GIFSTRIP prints lines describing the internal sections of the file. There are two major types of internal sections: images and extension blocks. The GIF89a format describes several types of dedicated extension block; GIFSTRIP recognizes these and names them as it finds them. 3.2.1 Image ----------- An example of an image line is: G-S ( 0, 0) 250 x 200 @ 128 20970BY 83BL The first column contains three flags. The first flag is "G" if this image uses the global color table, or "L" if it uses a local color table. The second column is "S" if there is a local color table and it is sorted, or "-" if not. It will always be "-" for GIF87a files. The third flag is "S" if the image lines are stored sequentially or "I" if the image lines are stored in an interlaced format. The next two columns, not including the parentheses etc., are the coordinates of the upper left corner of the image on the logical screen. These coordinates are in the format (horizontal offset to right, vertical offset down), measured in pixels from the upper left corner of the logical screen (0,0). The next two columns, not including the 'x', are the width and height of the image, in pixels. The following column, not counting the '@', is the number of colors in the global or local color table, depending on which the image uses. The last two columns are the number of bytes and blocks in the image, respectively. In the example, there are 20970 bytes of image data, which are broken up into 83 blocks. If GIFSTRIP encounters in an image one of the format violations listed under the -n NOSTRICT option, and that option is not in effect, it will print a message describing the violation _before_ it prints the image line for that image. This message will start with "FYI:". 3.2.2 Extension Block --------------------- When an extension block is encountered, GIFSTRIP will print one of several lines. If the format is GIF87a, or the extension block is not one of the four dedicated types defined in GIF89a, GIFSTRIP prints: Type xxx Extension Block where xxx is the type number given in the extension block header. If it is one of the four dedicated types defined under GIF89a, GIFSTRIP prints: Plain Text Extension Block Graphic Control Extension Block Comment Extension Block Application Extension Block as appropriate. After identifying the extension type, GIFSTRIP then prints the number of bytes and blocks in the extension block, on the same line, in the same format as for an image. 3.2.3 Other Lines ----------------- GIFSTRIP may issue error messages at any time. These will begin with "WARNING:", "ERROR:" or "FATAL ERROR:". There are two other messages that GIFSTRIP may issue: If GIFSTRIP is used with the -m MAC option and encounters leading junk bytes, it prints an "FYI:" message stating that leading junk bytes have been skipped over and gives the number of bytes skipped. This message appears before the file header line. If GIFSTRIP encounters extraneous characters between sections, it will issue an "FYI:" message describing the violation and giving the number of extraneous characters. This message appears between the lines describing the sections on either side of the extraneous characters. This is an FYI message because, technically, GIFSTRIP can fix the problem. However, extraneous characters between sections are forbidden by the format specification. If present, they indicate a serious problem in the encoder which produced the image, or, more likely, a corrupt GIF file. 3.3 Terminator Line ------------------- If the file is not corrupt, GIFSTRIP will eventually come to the GIF format terminator character. When it encounters this, it prints: GIF Terminator and ceases processing the original file. It then determines whether the file needs to be rebuilt or not. 3.4 No Rebuild -------------- If the file does not need to be rebuilt, GIFSTRIP prints: No work to be done. File unchanged. and proceeds to the next file. 3.5 Rebuild ----------- If the file does need to be rebuilt, either due to extra characters or format violations, GIFSTRIP prints: New size: xxx Bytes removed: yyy Recopying... done. where xxx is the size in bytes of the rebuilt file, and yyy is the difference between the size of the original file and the size of the rebuilt file. The next line ("Recopying...") is simply to indicate that GIFSTRIP is doing something. When GIFSTRIP prints "done." it is finished writing the rebuilt file and proceeds to the next file. The time and date of the original file are preserved in the rebuilt file. 3.6 Examples ------------ C:\>gifstrip g:\junk\vla.gif Processing G:\JUNK\VLA.GIF... GIF87A G-- 21470 250 x 200 @ 128 G:\JUNK\VLA.GIF G-S ( 0, 0) 250 x 200 @ 128 20970BY 83BL GIF Terminator New size: 21463 Bytes removed: 7 Recopying... done. This file is a GIF87a format file. It has a global color table. The file is 21463 bytes long. The logical screen is 250 pixels wide and 200 pixels high. The global color table contains 128 colors. The name of the file is "VLA.GIF" and it is in directory "\JUNK" on drive G:. This file contains one image. The image uses the global color table and is not interlaced. The upper left corner of the image is offset from the upper left corner of the logical screen by zero pixels horizontally and zero pixels vertically. The image is 250 pixels wide and 200 pixels high. The image has 128 colors. There are 20970 bytes of image data divided into 83 blocks. There is a GIF terminator. There were seven extra characters, so the file is rebuilt. C:\>gifstrip g:\junk\vla.gif Processing G:\JUNK\VLA.GIF... GIF87A G-- 21463 250 x 200 @ 128 G:\JUNK\VLA.GIF G-S ( 0, 0) 250 x 200 @ 128 20970BY 83BL GIF Terminator No work to be done. File unchanged. This example is the same file after it has already been stripped once. Since there are no extra characters and no format violations, it is not rebuilt. C:\>gifstrip -f g:\junk\vla.gif Processing G:\JUNK\VLA.GIF... GIF87A G-- 21463 250 x 200 @ 128 G:\JUNK\VLA.GIF G-S ( 0, 0) 250 x 200 @ 128 20970BY 83BL GIF Terminator New size: 21463 Bytes removed: 0 Recopying... done. This example is the same file yet again, but the forced rebuild option is in effect. The size of the rebuilt file is the same as the size of the original file. C:\>gifstrip g:\junk\cg89a.gif Processing G:\JUNK\CG89A.GIF... GIF89A G-- 26624 320 x 200 @ 256 G:\JUNK\CG89A.GIF Comment Extension Block 161BY 1BL FYI: Ignoring illegal local color table size (no local color table). G-S ( 0, 0) 170 x 110 @ 256 12200BY 48BL Plain Text Extension Block 24BY 2BL Graphic Control Extension Block 4BY 1BL Plain Text Extension Block 22BY 2BL FYI: Ignoring illegal local color table size (no local color table). G-S (150, 90) 170 x 110 @ 256 12767BY 51BL Plain Text Extension Block 26BY 2BL Graphic Control Extension Block 4BY 1BL Plain Text Extension Block 24BY 2BL Graphic Control Extension Block 4BY 1BL Plain Text Extension Block 20BY 2BL Comment Extension Block 417BY 2BL GIF Terminator New size: 26624 Bytes removed: 0 Recopying... done. This file is a GIF89a format file. It has a global color table. The global color table is not sorted. There is no aspect ratio data. The file is 26624 bytes long. The logical screen is 320 pixels wide and 200 pixels high. The global color table contains 256 colors. The filename is "CG89A.GIF" and is in directory "\JUNK" on disk G:. This file contains two images and ten extension blocks, all of which were recognized and which represent three of the four recognized types. First, there is a Comment Extension Block, containing 161 bytes of data in one block. Second, there is an image. It has a nonzero local color table size but the local color table flag is not set, so an FYI message is printed out before the image information. The image uses the global color table and is not interlaced. The upper left corner of the image is offset from the upper left corner of the logical screen by zero pixles horizontally and zero pixels vertically. The image is 170 pixels wide by 110 pixels high, and has 256 colors. There are 12200 bytes of image data, divided into 48 blocks. Third is a Plain Text Extension Block, containing 24 bytes of data in two blocks. Fourth is a Graphic Control Extension Block. These always contain four bytes of data in one block. Fifth is a Plain Text Extension Block, containing 22 bytes of data in two blocks. Sixth is an image. It has a nonzero local color table size byt the local color table flag is not set, so an FYI message is printed out before the image information. The image uses the global color table and is not interlaced. The upper left corner of the image is offset from the upper left corner of the logical screen by 150 pixels horizontally (to the right) and 90 pixels vertically (down). The image is 170 pixels wide by 110 pixels high, and has 256 colors. There are 12767 bytes of image data, divided into 51 blocks. Seventh is a Plain Text Extension Block, containing 26 bytes of data in two blocks. Eigth is a Graphic Control Extension block. Ninth is a Plain Text Extension Block, containing 24 bytes of data in two blocks. Tenth is a Graphic Control Extension block. Eleventh is a Plain Text Extension Block, containing 20 bytes of data in two blocks. Twelfth and lastly, there is a Comment Extension Block containing 417 bytes of data in two blocks. There is a GIF terminator. There were no extra characters, but there were format violations, so the file is rebuilt. The size of the rebuilt file is the same as the size of the original file. If the -n NOSTRICT option had been used, the FYI messages would not have been printed and the file would not have been rebuilt. 4. THE END ---------- Technical support via email is available from the following addresses: INTERNET (the following are alternate addresses for the same place): support@picarefy.com picarefy!support@amc.com picarefy!support@netcom.com uunet!uw-coco!amc-gw!picarefy!support COMPUSERVE: 71261,1731 GENIE: J.BIRDSALL2 Registrations should be sent to: James W. Birdsall 11112 NE 124 LN #D204 Kirkland, WA 98034 If you have an email address on any of the networks listed above, please include it when registering. It is much easier to send updates by email. Also, please specify what sort of archive (ZIP, ZOO, ARC, LZH, ARJ, UNIX shar) you can handle most easily. NOTE: IF YOU DO NOT PROVIDE AN EMAIL ADDRESS, YOU WILL ONLY RECEIVE MAJOR VERSION UPDATES. YOU WILL NOT RECEIVE MINOR VERSIONS. PLEASE PROVIDE AN EMAIL ADDRESS IF YOU HAVE ANY WAY OF DOING SO.